ShaderNodeSL¶

A SL programmable shader node. Double click SL nodes to edit the SL code in the console. This node uses a SL script to shade. SL boxes may contain more than a single function, but the returned value is taken from the last function. A SL function is a prototype declaring the return type, the function name and the function arguments. Arguments may also be output values.
For instance:

color myFunc (float A; color B)
{
        return A * B;
}

computes the product of the input float called A and the input color B. The compiled script automatically creates 2 inputs A and B, and an output Output. You can also add several outputs by specifying the output keyword before the argument type. Ex:

color myFunc (float A; color B; output color Half)
{
        Half = B * 0.5;
        return A * B;
}

You add meta-information in the SL comments to customize the SL node template in the UI:

// %param A = {type=types.float{min=0,slidermax=1,step=0.1},name="DisplayAsA"}
// %param B = {type=types.color,name="DisplayTab/AsB"}
color myFunc (float A; color B; output color Half)
{
        Half = B * 0.5;
        return A * B;
}

Possible meta-information on parameters are:

name: a '/' separated string. Ex: name="Tab/Subtab/Item" will display the parameter in the Tab > Subtab hierarchy, as Item
type: a Guerilla type. See types description in Guerilla SDK. Ex: type=types.float{min=0,max=1}, type=types.color, ...
hidden: the parameter is not visible in the node. Ex: hidden=true
exposed: the parameter is automatically exposed. Ex: exposed=true
help: a help string to be display in a tooltip. Ex: help="A protip for Guerilleros!"

Most Renderman SL functions are available, nevertheless there are some restrictions:

if control statement is currently not supported, and for control statement is partly supported.
the gather loop is not supported.

Texture

color texture (string filename, float s, float t, ...)
color environment (string filename, vector v, ...)

Read a texture by its file name and its texture coordinates (s,t) or a 3d direction (v).

texture accepts additional optional parameters, as pairs of string and value:

float "%1": replace the first "%d" pattern of the texture filename by this number. Can be used to specify a udim number or a frame number in a texture sequence.
float "%2": replace the second "%d" pattern of the texture filename by this number. Can be used to specify a udim number or a frame number in a texture sequence.
float "alpha": if 1.0, returns the alpha component of the texture. If 0.0, returns the color components.
float "blur": the filter minimum size. Default is 0. Blur the texture lookup using a fixed filter size. A blur of 1.0 means the filter size is the image size.
string "channel": the texture channel name to return. Only available with PSD files.
color "default": the color to return if no texture name is provided. Defaut is white.
string "filter": the filter kernel name to use, either "box", "triangle" (default), "gaussian" or "bspline"
float "gamma": the texture gamma as a float or a string, which indicates in which gamma color space the texture is. Can be a float gamma value (like 2.2), "sRGB" or "linear".
color "missing": the color to return if the texture is missing. Defaut is pink.
string "mode": the texture clamping mode, a string of 2 characters, the first for s mode and the second for t mode, "cc" for clamp/clamp, "ww" for wrap/wrap (default)
float "samples": an indicative number of anisotropic texture samples to filter at every texture lookup, default is 16.
float "width": the filter size multiplier. Default is 1. If width is greater than 1.0, the filter is more blurry. If lower than 1.0, the filter is sharper.

Note:

The texture must have been built previously with matching filter and mode parameters.
texture is not yet supported in realtime.
Guerilla normally uses Guerilla texture path which has been built, and is not the original bitmap path. For reasons of convenience, you can still use the bitmap file path, but Guerilla will assume a predefined path for the texture using given filter and clamp parameters. For instance, texture ("/a/path/to/my/bitmap.tiff", s, t) will use "/a/path/to/my/.guerilla/bitmap.tiff_triangle_ww" as input texture, while texture ("/a/path/to/my/bitmap.tiff", s, t, "filter", "gaussian", "mode", "cc") will use "/a/path/to/my/.guerilla/bitmap.tiff_gaussian_cc" as input texture.

In an SL Box, declare you file name parameter as types.texture to benefit from Guerilla's preview and handy UI:

// %param[Texture,types.texture]

color MyOwnTexture (string Texture = "")

{

    return texture (Texture, s, t);

}

Occlusion and Indirect diffuse

color occlusion (point p, vector dir, float samples, ...)
color indirectdiffuse (point p, vector dir, float samples, ...)

Compute occlusion/indirect diffuse from the given position p, in the given direction dir.

occlusion and indirectdiffuse accept additional optional parameters, as pairs of string and value:

float coneangle: The cone opening of the gather, in radians. PI/2 for full hemispherical gather
float raylength: The maximum ray length for the gather function
string environmentmap: The environment map texture
string filter: The environment map texture filter
float blur: The environment map texture blur
float gamma: The environment map texture gamma
matrix matrix: The environment map texture transform, as a matrix
color hitcolor: The occlusion hit color, default is 0 black
color skycolor: The sky color, in case no environmentmap is provided, default is 1 white
float bentnormal: Compute bent normal occlusion when 1

Option "pointbased" indicates that the gather function must use a specific point based cloud, instead of raytracing. By default, the gathering uses raytracing.

Here are the raytracing options:

string subset: The subset of objects to trace
float opacity: Indicates that the hit objects must be shaded for opacity, so one can compute occlusion on semi transparent objects.
float depth: The maximum recursive raytracing depth.
string value: Indicates the surface shader output to use instead of Ci. If said output doesn't exist in the shader, the shading engine will revert to Ci.
float lastrayenv: If 0, the rays deeper than the maximum depth return the sky color, else they return the environment

Guerilla expects subset to be a correct value, and unless you crafted you RIB files, which is most unlikely, you can't know this value. To be able to use subsets, simply declare your subset parameter as a types.trace, which will let you connect the SL Box just like any raytracing node:

// %param[Trace,types.trace]

color MyOwnOcclusion (string Trace = "")

{

    return occlusion (P, N, 16, "subset", Trace);

}

Here are the point based options (i.e. when "pointbased" 1 is specified):

string filename: The point based cloud file to use
float maxsolidangle: The maximum solid angle
float rasterize: gather uses rasterization.
float usebackface: gather uses surfels back side.

Note: varying coneangle and raylength are not supported for point based gathering.

Guerilla expects filename to be a correct point cloud name, and unless you crafted you RIB files, which is most unlikely, you can't know this value. To be able to use Guerilla point cloud, simply declare your filename parameter as a types.pointcloud, which will let you connect the SL Box just like any point based gathering node:

// %param[PointCloud,types.pointcloud]

color MyOwnPBOcclusion (string PointCloud = "")

{

    return occlusion (P, N, 16, "pointbased", 1, "filename", PointCloud);

}

SL functions

Here is the exhaustive list of supported functions. For more detail on function behaviour, please refer to the Renderman SL reference.

any is a shortcut for float|vector|point|normal|color.

Basic mathematical functions

Absolute value of x	any abs (any x)
Sign of x	any sign (any x)
Minimum between x and y	any min (any x; any y)
Maximum between x and y	any max (any x; any y)
Clamp x between xmin and xmax	any clamp (any x; any xmin; any xmax)
Mix between x and y, as (1-a)x+ay	any mix (any x; any y; any a)
Highest integer smaller or equal to x	any floor (any x)
Smallest integer greater or equat to x	any ceil (any x)
Closest integer to x	any round (any x)
x raised to the power of y	float pow (float x; float y)
Exponential of x	float exp (float x)
Square root of x	float sqrt (float x)
Inverse square root of x	float inversesqrt (float x)
Neper logarithm of x	float log (float x)
Modulus of x	float mod (float x; float modulo)

Trigonometric functions

Radians to degrees	float degrees (float angle)
Degrees to radians	float radians (float angle)
Sine of angle in radians	float sin (float angle)
Radians arcsine of x	float asin (float x)
Cosine of angle in radians	float cos (float angle)
Radians arccosine of x	float acos (float x)
Tangent of angle in radians	float tan (float angle)
Radians arctangent of x	float atan (float x)
Radians arctangent of y/x	float atan (float y; float x)
Radians arctangent of y/x	float atan2 (float y; float x)

Step functions

Hard step, equivalent to x >= edge ? 1 : 0	float step (float edge; float x)
Linear step between xmin and xmax	float boxstep (float xmin; float xmax; float x)
Cubic step between xmin and xmax	float smoothstep (float xmin; float xmax; float x)
Filtered step, 1 pixel antiliasing for filterwidth=0.5	float filterstep (float edge; float value; float filterwidth)

Derivatives

Derivative of x over u	float Du (float x)
Derivative of x over u	color Du (color x)
Derivative of x over u	vector Du (point\|vector\|normal x)
Derivative of x over v	float Dv (float x)
Derivative of x over v	color Dv (color x)
Derivative of x over v	vector Dv (point\|vector\|normal x)

Geometric functions

Extract x component of v	float xcomp (vector\|point\|normal v)
Extract y component of v	float ycomp (vector\|point\|normal v)
Extract z component of v	float zcomp (vector\|point\|normal v)
Extract nth component of c	float comp (color c; float component)
Euclidean length of v	float length (vector\|point\|normal v)
Normalized v	vector\|normal normalize (vector\|normal v)
Euclidean distance between a and b	float distance (point a; point b)
Flips v if opposite to i	vector\|normal faceforward (vector\|normal v; vector\|normal i)
Flips v if opposite to i	vector\|normal faceforward (vector\|normal v; vector\|normal i; vector\|normal n)
Reflected direction of v to n	vector\|normal reflect (vector\|normal v; vector\|normal n)
Refracted direction of v to n, with eta relative IOR	vector\|normal refract (vector\|normal v; vector\|normal n; float eta)
Transforms point p from current to given space	point transform (string space; point p)
Transforms point p from fromspace to tospace	point transform (string fromspace; string tospace; point p)
Transforms vector v from current to given space	vector vtransform (string space; point p)
Transforms vector v from fromspace to tospace	vector vtransform (string fromspace; string tospace; vector v)
Transforms normal n from current to given space	normal ntransform (string space; point p)
Transforms normal n from fromspace to tospace	normal ntransform (string fromspace; string tospace; normal n)
Computes normal from point p	normal calculatenormal (point p)

Noise and clouds

Random value between 0 and 1	float\|color\|point random ()
1d perlin noise on x	float\|color\|point noise (float x)
2d perlin noise on x and y	float\|color\|point noise (float x; float y)
3d perlin noise on xyz	float\|color\|point noise (vector\|point\|normal xyz)
4d perlin noise on xyz and w	float\|color\|point noise (vector\|point\|normal xyz; float w)
1d periodic perlin noise on x	float\|color\|point pnoise (float x, uniform float px)
2d periodic perlin noise on x and y	float\|color\|point pnoise (float x; float y, uniform float px; uniform float py)
3d periodic perlin noise on xyz	float\|color\|point pnoise (vector\|point\|normal xyz, uniform vector\|point\|normal pxyz)
4d periodic perlin noise on xyz and w	float\|color\|point pnoise (vector\|point\|normal xyz; float w, uniform vector\|point\|normal pxyz; uniform float pw)
1d cellular perlin noise on x	float\|color\|point cellnoise (float x)
2d cellular perlin noise on x and y	float\|color\|point cellnoise (float x; float y)
3d cellular perlin noise on xyz	float\|color\|point cellnoise (vector\|point\|normal xyz)
4d cellular perlin noise on xyz and w	float\|color\|point cellnoise (vector\|point\|normal xyz; float w)

String manipulation

Print a string, equivalent to the C printf function	void printf (string fmt, ...)
Build a string, equivalent to the C sprintf function	string format (string fmt, ...)
	float atof (string str)

Misc functions

float shadert ()

Volumetrics

color voxel (point P; string channel; ...)

the voxel function makes a lookup in the current 3d voxel object. If the shaded object is not a 3d voxel it returns the default color.

Example :

color density = voxel (P, "density", "filter", "linear");

voxel accepts the following parameters (the 3 first are mandatory):

	point P	Lookup position in camera space.
	string channel	The voxel channel name to lookup.
"velocitychannel"	string velocitychannel = ""	the velocity channel to use for the motion blur. Default is "", no motion blur.
"velocityfactor"	float velocityfactor = 1	the velocity factor. A factor to enhance/reduce the motion blur effect. Default is 1.
"default"	color default = 0	the default value to return if the lookup is out of the voxel or if there is no voxel. Default is (0,0,0).
"filter"	string filter = "linear"	The filter to use during the lookup. "nearest" : no filtering, "linear" : linear filtering (sharper), "cubic" : cubic filtering (smoother, slower).
"propagate"	float propagate = 0	If != 0, propagate the border values outside the voxel. This option has no effect with openvdb voxels. Default is 0 : no propagation, returns the default value outside of the voxel.